Claude Code (CC)

Anthropic‘s AI coding agent.

General usage guidelines

There is a free course by Anthropic: Claude Code in Action

The creator of Claude Code (CC) Boris Cherny himself wrote a thread: a thread on how he uses CC.

Don’t over-engineer

The base LLMs are getting increasingly capable and generally evolve towards a direction where carefully crafted prompts, tools, and crutches become unnecessary. Because of base LLMs’ raw power and the rapid development, it may not be a good idea to spend too much time building extra infrastructure, skills, tools, etc. around CC. Soon, they may become obsolete, or worse, they can restrict CC’s power by imposing too much constraints while creating maintenance burden.

Think about verification

Although code generation is becoming so easy, verification is still not trivial. You want to think & invest more in verification. CC also works best when it can verify its own work. Write tests (or ask to write tests), check those tests, create scaffolding for verifying the work.

Use plan mode

Shift + Tab cycles through the three modes: normal, plan, accept-edits. At the beginning of a task, it is a good idea to use the plan mode. When prompted in the plan mode, CC asks you to clarify requirements and spend more context to have a broader understanding of the whole codebase.

Use git commit as checkpoints

Don’t just let CC write huge amount of code without any commits. Try to regularly commit, each of which becomes the checkpoint that you can revert back if things go wrong. It is probably good idea to commit when all the tests pass and you are confident about the current state of the code (cf. the Test driven development loop).

Use plain text (markdown) documents

CC has massive context window. Still, try to document, document, document. When CC behaves in an undesired manner, prevent it by writing it down in CLAUDE.md. When there is a list of todo items, create a document and use it as an intermediary medium between you and CC. Do you have high-level design principles that should be applied consistently across the project, be sure to keep it written down. Make things cumulative.

Basic settings

The preferences and settings are stored in CLAUDE.md (at project root or in .claude/) and .claude/settings.json. CLAUDE.md is for natural language instructions such as project overview, tool preferences, directory structure, etc. and settings.json is a structured file for explicit permissions, hooks, plugins, etc. There are three types of CLAUDE.md:

In CC session, you can type # and that initiate the “memory mode” where you can add instructions to one of those CLAUDE.md files.

See the Official documentation for more details.

Global preferences

You can create global CLAUDE.md and settings.json and put it in ~/.claude/ directory, which is used by Claude to store various temporary files and settings. These settings and preferences are applied to every CC sessions unless overridden by project-specific settings.

You can incorporate these files into your dotfiles repo.

Tips

If you’re annoyed by manually approving trivial commands, add them the pre-approved list. These can be stored in the global setting file. You can ask CC to create one.

You can also ask CC to set up certain hooks. For instance, you can ask it to run a linter/fixer (e.g., ruff) whenever a script is edited or created. CC will automatically run it.

Skills

You can equip CC with skills. Each skill is a markdown document containing specific instructions for a task, optionally accompanied by scripts.

See the Official documentation for more details.

Creating Skills

Skills are stored as SKILL.md files in .claude/skills/SKILL_NAME/ (project-level) or ~/.claude/skills/SKILL_NAME/ (global). Each skill file contains a YAML header with a description of when the skill should be used, step-by-step instructions for CC to follow, and optional references to helper scripts.

The YAML header requires:

When CC is launched, only the YAML headers of available skills are loaded to CC’s context. They are used as an index for CC. CC uses these descriptions to determine which skills to invoke.

Example: A Minimal Math Skill

~/.claude/skills/math/
├── SKILL.md
└── verify.py

The SKILL.md file may look like:

---
name: math
description: >
  Verify mathematical derivations step-by-step using SymPy.
  Use this when users ask to verify proofs, check calculations,
  or solve symbolic math problems.
---

When the user asks you to verify or solve mathematical problems:

1. Use the bundled `verify.py` script for symbolic computation
2. Show step-by-step derivation
3. Verify the final result

## Usage

Run the verification script:

    # Check two expressions are equal
    ~/.claude/skills/math/verify.py eq "EXPR1" "EXPR2"

    # Simplify/expand expression
    ~/.claude/skills/math/verify.py simp "EXPR"

Always explain your reasoning alongside the output.

A skill may or may not have accompanying scripts. It can have no script at all (just instructions) or simple inline code examples.

Using Skills

Skills are not invoked by the user, but only by CC. Skills are exposed to CC based on the YAML header. When CC determines that the skill is applicable, it will invoke the skill. When invoked, CC reads the full skill file and follows its instructions.

The “math skill” shown above would be invoked automatically when you ask CC to check derivation of some mathematical formula.

Skills essentially let you encode repeatable workflows as reusable “recipes” that CC can execute on demand.

Installing Skills from Plugin Marketplace

CC provides a built-in plugin marketplace for easy skill installation. Use the /plugin marketplace add command:

/plugin marketplace add <github-repo>

For example, to install the official Anthropic skills:

/plugin marketplace add anthropics/skills

This command:

  1. Fetches the GitHub repository (e.g., github.com/anthropics/skills)
  2. Downloads all skill files (.md and associated scripts)
  3. Installs them to your .claude/plugins/ directory

Note that these skills are not automatically available. You need to explicitly enable them by invoking /plugin command or manually editing .claude/settings.json (project-level) or ~/.claude/settings.json (global):

{
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true,
    "document-skills@anthropic-agent-skills": true,
    "example-skills@anthropic-agent-skills": true
  }
}

Checking available skills and using them

In CC, you can check available skills by running:

/skills

If the skills are correctly installed, you should see the list of available skills. They will be invoked when necessary.

Skill Collections

Several community repositories provide curated collections of ready-to-use skills:

Tips

General tips

tmux + Neovim Setup

If you prefer terminal-based light-weight setup over IDEs like cursor, a nice way is to have a tmux session per project with Claude Code and an editor (e.g., Neovim) open side by side. You read, check, and edit with Neovim while asking things to Claude Code. When doing this, it is critical for Neovim to auto-reload files when Claude Code edits them externally. Without this setup, you’ll be viewing stale files unless you force-reload with :e!, which creates an annoying situation with unsaved edits in the current buffer that diverged from the file content.

To do so, you have to configure tmux correctly in addition to Neovim.

Neovim configuration

Add to your Neovim config (e.g., lua/user/options.lua):

-- Auto-reload files when changed externally
vim.o.autoread = true
vim.api.nvim_create_autocmd({ 'FocusGained', 'BufEnter' }, {
  command = 'checktime',
})

tmux configuration

Add to your tmux.conf:

set -g focus-events on

This tells tmux to forward focus events to Neovim. Without it, Neovim won’t know when you switch back to it and won’t trigger the FocusGained autocmd.

Applying changes

For Neovim, restart or source your config. For tmux, either restart tmux, or run tmux set -g focus-events on in the terminal, or run Ctrl+a (or your prefix) then : and type set -g focus-events on inside tmux.